home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 2002 November / SGI Freeware 2002 November - Disc 2.iso / dist / fw_groff.idb / usr / freeware / catman / u_man / cat5 / groff_tmac.Z / groff_tmac
Text File  |  2002-04-08  |  10KB  |  224 lines
  1. GROFF_TMAC(5)                        GROFF_TMAC(5)
  2.  
  3.  
  4.  
  5. NNAAMMEE
  6.        groff_tmac - macro files    in the roff typesetting    system
  7.  
  8. DDEESSCCRRIIPPTTIIOONN
  9.        The  rrooffff(7)  type-setting  system provides a set of macro
  10.        packages    suitable for special kinds  of    documents.   Each
  11.        macro  package stores its macros    and definitions    in a file
  12.        called the package's ttmmaacc ffiillee.    The name is deduced  from
  13.        `TTroff MMAACCros'.
  14.  
  15.        The  tmac  files     are normal roff source    documents, except
  16.        that they usually contain only definitions and setup  com
  17.        mands,  but  no text.  All tmac files are kept in a single
  18.        or a small number of directories, the ttmmaacc directories.
  19.  
  20. NNAAMMIINNGG
  21.        In classical  roff  systems,  there  was     a  funny  naming
  22.        scheme.     If  the name of a macro package started with `mm'
  23.        this letter was omitted,    e.g., the macro    package     for  the
  24.        man  pages  _m_a_n    was  called _a_n and its macro file _t_m_a_c_._a_n
  25.        (note that in recent versions of    groff this file    is called
  26.        _a_n_._t_m_a_c instead).
  27.  
  28.        By  a similar reasoning,    macro packages that did    not start
  29.        with an `mm' were    often referred to by adding an `mm', e.g.,
  30.        the  package  corresponding  to    _t_m_a_c_._d_o_c  was called _m_d_o_c
  31.        because the command-line    for activating it reads
  32.  
  33.           ttrrooffff --mm_d_o_c.
  34.  
  35.        Actual versions of ggrrooffff(1) provide  both  naming  schemes
  36.        for  the     inflicted  macro  packages, with and without the
  37.        leading `mm'. So in _g_r_o_f_f, the _m_a_n  macro     package  may  be
  38.        specified as
  39.  
  40.           ggrrooffff --mm _m_a_n,
  41.           ggrrooffff --mm_a_n,
  42.           ggrrooffff --mm_m_a_n, or
  43.           ggrrooffff --mm _a_n.
  44.  
  45.        The  easiest  way  to  find  out     which macro packages are
  46.        available on a system is    to check the contents of the _t_m_a_c
  47.        directories.   For example, a file called ttmmaacc.._a_n_y_t_h_i_n_g or
  48.        _a_n_y_t_h_i_n_g..ttmmaacc determines    a macro    package    named _a_n_y_t_h_i_n_g.
  49.  
  50.        In _g_r_o_f_f, most macro packages are described in  man  pages
  51.        called ggrrooffff__<<nnaammee>>(7), with a leading `mm' for the classi
  52.        cal packages.
  53.  
  54. IINNCCLLUUSSIIOONN
  55.        There are several ways to use a    macro  package    in  docu
  56.        ments.    At  run-time,  the groff option    --mm _n_a_m_e    makes the
  57.        definitions in  the  macro  file     _n_a_m_e..ttmmaacc  available  as
  58.        described  in  the  section  NNAAMMIINNGG.   If  this file isn't
  59.        found, ttmmaacc.._n_a_m_e    will be    searched.
  60.  
  61.        It is also possible to include the  macro  file    into  the
  62.        document     by using the groff requests ..ssoo or ..mmssoo. For ..ssoo
  63.        the full    filename of the    macro file must    be  specified  --
  64.        including  the  directory  where    it is kept.  If    the macro
  65.        file is stored in one of    the tmac directories it     is  more
  66.        convenient  to  use  ..mmssoo  instead because it searches the
  67.        tmac path for the filename.   Additionally,  if    the  file
  68.        name  to     be  included has the form _n_a_m_e..ttmmaacc and it isn't
  69.        found, ..mmssoo will    try to open ttmmaacc.._n_a_m_e  instead    and  vice
  70.        versa.
  71.  
  72.        Note  that  in  order to    resolve    the ..ssoo    and ..mmssoo requests
  73.        the roff    preprocessor ssooeelliimm must be called if  the  files
  74.        to  be  included     needs    preprocessing.     This can be done
  75.        either directly by a pipeline on    the command  line  or  by
  76.        using the --ss option of ggrrooffff.
  77.  
  78.        You  can     also  supply  the letter `ss' in the preprocessor
  79.        word as described in section CCOONNVVEENNTTIIOONN.
  80.  
  81.        For example, suppose a macro file is stored as  _/_u_s_r_/_f_r_e_e_
  82.        _w_a_r_e_/_s_h_a_r_e_/_g_r_o_f_f_/_1_._1_7_._2_/_t_m_a_c_/_m_a_c_r_o_s_._t_m_a_c     and  is  used in
  83.        some document called _d_o_c_u_._r_o_f_f.
  84.  
  85.        At run-time, the    formatter call for this    is
  86.  
  87.           ggrrooffff --mm _m_a_c_r_o_s _d_o_c_u_._r_o_f_f
  88.  
  89.        To include the macro file directly in the document either
  90.           .mso macros.tmac
  91.        is used or
  92.           .so                       /usr/free
  93.           ware/share/groff/1.17.2/tmac/macros.tmac
  94.  
  95.        In both cases, the formatter is called with
  96.           groff -s docu.roff
  97.  
  98. CCOONNVVEENNTTIIOONN
  99.        There  is  a  convention     that is supported by many modern
  100.        roff type-setters: the pprreepprroocceessssoorr wwoorrdd    described in  the
  101.        following.
  102.  
  103.        If  the    first  line in a document is a comment,    the first
  104.        word (after the comment characters and  a  blank)  consti
  105.        tutes  the pprreepprroocceessssoorr wwoorrdd.  That means that the letters
  106.        of this word are    interpreted as    abbreviations  for  those
  107.        preprocessor  commands  that should be run when formatting
  108.        the document.  Mostly, only the letters    corresponding  to
  109.        the  options  for  the  preprocessors are recognized, `ee',
  110.        `GG', `gg', `pp', `RR', `ss',    and `tt'    (see rrooffff(7)).
  111.  
  112.        Besides being a good reminder for the user,  some  format
  113.        ters  (like the mmaann(1) program) are even    able to    automati
  114.        cally start the preprocessors specified in the  preproces
  115.        sor word, but do    not bet    on this.
  116.  
  117. WWRRIITTIINNGG    AA MMAACCRROO    FFIILLEE
  118.        Writing    a  groff  macro     file  is  easy.  Design a set of
  119.        macros, strings,    registers, etc.     Store them in    a  single
  120.        file.   Documents  that    use the    macros include this macro
  121.        file with the ..ssoo request as described  in  the    IINNCCLLUUSSIIOONN
  122.        section.
  123.  
  124.        To  use    the tmac functionality,    call the macro file _w_h_a_t_
  125.        _e_v_e_r..ttmmaacc (or ttmmaacc.._w_h_a_t_e_v_e_r) and    put it in some    directory
  126.        of  the    tmac path, cf. section FFIILLEESS.  Then documents can
  127.        include it with the ..mmssoo    request    or the ggrrooffff --mm    option as
  128.        described in the    IINNCCLLUUSSIIOONN section.
  129.  
  130.        If your macros might be of general usage    contact    the groff
  131.        maintainers to have them    included  in  the  groff  _c_o_n_t_r_i_b
  132.        source directory.
  133.  
  134.        Some  general  guidelines  might     be  helpful  in  writing
  135.        macros.
  136.  
  137.     Double all functional backslashes, `\\' -> `\\\\'.
  138.  
  139.     All printable backslashes must be written as `\\ee'.
  140.  
  141.     Escape all dots, `..' ->    `\\..'.
  142.  
  143.     Make ample use of the non-printable  character    `\\&&'  in
  144.      text  parts,  esp.  before `\\'    and at the beginning of    a
  145.      line, but not before a    delayed    command.
  146.  
  147.     Use the    character `@@' in temporary variable names.
  148.  
  149.     Test your macros for text and graphical     devices,  e.g.,
  150.      _l_a_t_i_n_1    and _p_s.
  151.  
  152. FFIILLEESS
  153.        All  macro  names  must be named    _n_a_m_e..ttmmaacc or ttmmaacc.._n_a_m_e to
  154.        use the tmac mechanism.
  155.  
  156.        The macro files are kept    in the ttmmaacc ddiirreeccttoorriieess,  all  of
  157.        which constitute    the ttmmaacc ppaatthh..
  158.  
  159.        The  elements  of  the search path for macro files are (in
  160.        that order):
  161.  
  162.       the directories specified with troff's  resp.     groff's
  163.        --MM command line option
  164.  
  165.       the  directories given in the    GGRROOFFFF__TTMMAACC__PPAATTHH    environ
  166.        ment    variable
  167.  
  168.       the current directory    (only if in  unsafe  mode  using
  169.        the --UU command line switch)
  170.  
  171.       the home directory
  172.  
  173.       a  site-specific  (platform-independent)  directory, a
  174.        platform-specific directory,    and the    main tmac  direc
  175.        tory:
  176.  
  177.          /usr/freeware/share/groff/site-tmac
  178.          /usr/freeware/lib/groff/site-tmac
  179.          /usr/freeware/share/groff/1.17.2/tmac
  180.  
  181. EENNVVIIRROONNMMEENNTT
  182.        GGRROOFFFF__TTMMAACC__PPAATTHH
  183.           A     colon separated list of additional tmac directo
  184.           ries in which to search for macro    files.     See  the
  185.           previous section for a detailed description.
  186.  
  187. BBUUGGSS
  188.        The groff documentation is in evolution at the moment.  It
  189.        is possible that    small inconsistencies  between    different
  190.        documents exist temporarily.
  191.  
  192. AAUUTTHHOORR
  193.        This document is    part of    groff, the GNU roff distribution.
  194.        It was written by Bernd Warken <bwarken@mayn.de>.
  195.  
  196.        It is distributed under the terms of  the  FDL  (GNU  Free
  197.        Documentation  License)    version    1.1 or later.  You should
  198.        have received a copy of the FDL on your system, it is also
  199.        available on-line under
  200.  
  201.           _<_h_t_t_p_:_/_/_w_w_w_._g_n_u_._o_r_g_/_c_o_p_y_l_e_f_t_/_f_d_l_._h_t_m_l_>.
  202.  
  203. SSEEEE AALLSSOO
  204.        The authoritative source    of information for all details of
  205.        the groff system    is the groff iinnffoo(1) file.
  206.  
  207.        For a groff overview, see rrooffff(7) and the file  _R_E_A_D_M_E  in
  208.        the groff source    package.
  209.  
  210.        The   groff   tmac   macro   packages   are  ggrrooffff__mmaann(7),
  211.        ggrrooffff__mmwwwwww(7),     ggrrooffff__mmddoocc(7),       ggrrooffff__mmddoocc..ssaammpplleess(7),
  212.        ggrrooffff__mmee(7),    ggrrooffff__mmmm(7),     ggrrooffff__mmmmrrooffff(7),     and
  213.        ggrrooffff__mmss(7).
  214.  
  215.        The groff language is described in ggrrooffff(7) and    the  for
  216.        matters in ggrrooffff(1), ttrrooffff(1).
  217.  
  218.        The  Filesystem    Hierarchy  Standard (FHS) is available at
  219.        hhttttpp::////wwwwww..ppaatthhnnaammee..ccoomm//ffhhss//.
  220.  
  221.  
  222.  
  223. Groff Version 1.17.2       27 June 2001            GROFF_TMAC(5)
  224.